🤖 OpenSpec + Antigravity CLI 規範樣板手冊

本手冊定義了新專案如何透過 Antigravity CLI 與 OpenSpec 進行「規格驅動開發 (Spec-driven Development)」。請跟著以下步驟，為您的新專案建立完美的開發基礎。

⚠️ 先決條件 (Prerequisites)

在開始建立專案之前，請確保您的開發環境中已經安裝並能在終端機正常呼叫以下工具：

Git (命令列版本)：用於版本控制 (官方下載)
Node.js / npm：用於套件與工具管理 (官方下載)
Python 3：用於執行部分擴充腳本與工具 (官方下載)
*(注意：Windows 安裝時請務必勾選「Add Python to PATH」)*

第 0 項：建立專案目錄並進入

在終端機執行以下指令來建立並進入您的新專案：

mkdir my-new-project
cd my-new-project

第 1 項：初始化版本控制

為了避免不必要的大型檔案或隱私資訊進入版本控制，我們必須在專案一開始就建立 .gitignore 檔案。

請先建立 .gitignore 檔案，並貼上以下樣板內容：

venv/
node_modules/
__pycache__/
*.pyc
.DS_Store
.env
logs/
records/
*.db
*.log
*.csv

存檔後，請在命令列複製執行以下指令，完成身份確認與首次 Commit：

# 確保已設定全域名稱與信箱 (若已設定過可略過這兩行)
git config --global user.name "您的名字"
git config --global user.email "您的信箱"

# 初始化並進行首次提交
git init
git add .gitignore
git commit -m "chore: initial commit with gitignore"

第 2 項：產生專屬大腦結構

執行以下指令，為這個專案建立獨立的設定檔結構：

openspec init

重要提示：當系統詢問框架時，請選擇 antigravity。

第 3 項：核心觀念 (這些隱藏目錄是怎麼來的？)

執行完上面的 openspec init 指令後，您的專案目錄下會多出 .agent/ 與 openspec/ 兩個隱藏目錄。這就是您的專案「專屬大腦」：

.agent/：掌管 AI 的行為模式與鐵律（例如要求 AI 執行指令前必須取得同意、強制要求版控等）。
openspec/：負責儲存專案的系統規格、架構設計與任務狀態，確保每次對話都能延續專案的記憶。

透過這樣的分離，每個專案都有自己獨立的客製化設定與規格庫。

第 4 項：啟動 AI 並切換模型

執行以下指令啟動 Antigravity CLI：

agy init

啟動後，務必先將模型切換為 pro (High) 以獲得最佳的邏輯推理能力。

操作方式：在對話框輸入 /model 然後選擇 pro，或直接輸入 /model pro。

第 5 項：注入鐵律與設定

現在我們要將我們精心設計的專案鐵律與設定寫入剛剛產生的隱藏目錄中。

⚠️ 貼上前的注意事項

下方的指令中包含了 [填寫專案名稱] 與 [填寫技術棧] 兩個佔位符。請在送出給 AI 前，先將它們替換成您實際的專案名稱與預計使用的技術棧（例如：React, Node.js 等）。

請在 CLI 對話框中直接貼上並修改以下完整指令，讓 AI 一次幫您建好檔案：

/openspec-explore 請幫我建立新專案的基礎規範。

1. 請寫入以下內容到 `.agent/AGENTS.md` 檔案中：
# 專案鐵律 (Rules)
- **執行前確認 (Execution Confirmation)**：在修改檔案、執行指令或進行破壞性變更之前，永遠必須先向使用者提出計畫與變更內容，並取得明確同意後才可執行。
- **嚴格的版本控制 (Strict Version Control)**：在完成任何重大更新或功能後，永遠必須主動執行 `git add .` 與 `git commit`。
- **非同步任務同步 (Async Task Synchronization)**：當呼叫非同步的背景子代理或任務時，永遠必須等待回傳完成訊息後，才可進行 Git Commit 或分支操作。
- **防呆與錯誤處理 (Error Handling & Guardrails)**：在實作任何核心邏輯或 UI 互動時，必須主動考慮極端情況並加入適當的阻擋機制。
- **流程圖文件化 (Flowchart Documentation)**：產生的系統架構或邏輯流程圖，必須使用 `mermaid` 語法記錄到 Spec 文件中。
- **自動同步主文件 (Auto-Sync Master Docs)**：變更歸檔後，必須自動重新生成 `openspec/specs/README.md`。

2. 請寫入以下內容到 `openspec/config.yaml` 檔案中：
schema: spec-driven
context: |
  Project: [填寫專案名稱]
  Tech Stack: [填寫技術棧]
  Conventions:
    - 遵守 Conventional Commits 規範
    - 嚴格遵守 Spec-driven 的開發流程
  Language Requirement:
    - CRITICAL: 所有未來產出的 OpenSpec 文件絕對必須使用繁體中文 (zh-TW) 撰寫。
rules:
  proposal:
    - "Must be written in Traditional Chinese (zh-TW) / 所有提案必須以繁體中文撰寫"
  tasks:
    - "Must be written in Traditional Chinese (zh-TW) / 所有任務必須以繁體中文撰寫"
  specs:
    - "Must be written in Traditional Chinese (zh-TW) / 所有規格說明書必須以繁體中文撰寫"

完成後請告訴我。

第 6 項：開始協作與收尾

設定完成後，當您要開始任何新功能開發時，請依照標準的 OpenSpec 規格驅動開發 (SDD) 流程進行：

宣讀鐵律：在對話起手式，務必先要求 「請遵守 .agent/AGENTS.md 的鐵律」。
探索與討論：輸入 /openspec-explore 進入探索模式，與 AI 進行需求討論與架構推演。
建立提案與規格：討論收斂後，輸入 /openspec-propose。AI 會建立符合 SDD 規範的 proposal.md、design.md、tasks.md 等文件。
開發與實作：規格確立後，輸入 /openspec-apply-change 讓 AI 根據任務清單正式進行程式碼開發。
封存與歸檔：功能完成後，輸入 /openspec-archive-change 封存變更，系統會自動同步規格。

💡 如何接續對話？
如果您使用 Ctrl+D 離開 Antigravity CLI，日後只要再次執行 agy init，接著輸入 /resume 即可列出歷史對話；輸入對應的短 ID（例如 /resume <短ID>）就能直接恢復先前的記憶與工作狀態。

📝 專案收尾與文件化
當階段性開發告一段落時，請直接命令 AI 產出專案入口說明（例如：「請根據目前的系統實作進度，在根目錄產生一份 README.md，內容需包含系統說明、環境安裝與執行步驟。」），確保專案隨時保持易於接手的狀態。

第 7 項：[選用] 擴充功能：安裝對話匯出技能

如果您需要將 AI 的長篇對話匯出成 Markdown 文件（用於歸檔或分享），可以額外安裝對話匯出/匯入技能。

請在任一目錄下開啟終端機，下載該技能包並執行安裝腳本，您可以依照喜好選擇安裝到「當前專案」或「全域環境 (Global)」：

git clone https://github.com/WilliamFromTW/antigravity-chat-exporter.git
cd antigravity-chat-exporter
python install.py

安裝完成後，您隨時可以在對話中命令 AI：「請幫我匯出目前的對話」 或 「請匯出所有對話」，AI 就會自動呼叫腳本並為您產出完整的對話紀錄檔。

除此之外，您也可以直接在專案根目錄下點選 chat_history_viewer.html 即可，方便我們瀏覽。

注意事項(一)：系統工具升級指南

隨著工具的迭代，您可能會需要升級 Antigravity CLI 或 OpenSpec 框架：

🚀 升級 Antigravity CLI

直接在終端機輸入以下指令即可自動更新至最新版：

agy update

📦 升級 OpenSpec 框架

OpenSpec 的升級分為兩階段：
1. 首先需要在全域環境重新安裝最新版的 OpenSpec：

npm install -g @fission-ai/openspec@latest

2. 接著必須進入每一個既有專案的目錄下，強制更新專案內的設定結構：

openspec update --force

文件基於工具版本：openspec 1.6.0，agy 1.1.4